Volume 1

Issue 1

March 2004

Case Study Charles Cantrell, Ontario Systems A Case Study in Developing Dynamic Content at Ontario Systems Charles Cantrell, an Information Engineer, describes Ontario Systems' process for delivering dynamically assembled and populated documentation for Artiva, its "highly customizable" accounts receivable management application. Background Ontario Systems provides receivables management solutions to organizations that manage large volumes of accounts receivables. Our tools allow clients to automate workflow for collectors and account managers who may not be experienced in accounts. This automation provides clients with a competitive edge. Clients define their own workflows, based on their company's standards and practices. When the Artiva project began, FACS, Ontario Systems' flagship product, had a character-based user interface (CHUI ). Many industry experts considered FACS to be the industry's best, but the interface looked antiquated and the underlying code was difficult to modify. The company determined that the best way to deal with both problems was to develop a completely new product that incorporated our understanding of our clients' business processes and eliminated the difficulties in modifying the existing code. One of the key objectives in the new product was to incorporate modularized functionality, allowing us to build products for each niche market comprising our primary market. Modularized functionality would allow us to assemble core functional models to meet specific needs in each niche. A second key objective was to allow clients to tailor the user interface and workflow of their application to their individual business requirements. Our clients would use our underlying code to modify their application to their exact needs. Danger/Issues There were several risks to this proposal. One was the scope of work, and the resources this would take from continuing development of FACS. However, based on my responsibilities in Technical Communication, I was more concerned about how our team would provide documentation for a product that would have no fixed user interface and no fixed workflow processes. Goals and Opportunities Based on the company's plans, it was imperative that the Technical Communication team step up with new ideas for delivering documentation to our clients. Because of the modularized, customizable software, our goal was to create documentation that could be assembled based on how clients modified the software. Preliminary work showed that it was possible to attach components of documentation to various elements of the application. Further, it would be possible to assemble these individual "documentation units" into conceptual and procedural material. However, it was my opinion that this could be supported only if the content was written and stored as XML. What We Did and Why At the project's inception, our Technical Communication team was writing nearly all documentation in FrameMaker. We began by considering FrameMaker+SGML, but my research led me to believe that we needed a native XML application. I wanted tools as close to the XML standard as possible, and the ability to use a range of XML tools. During this period, I wrote a small "proof of concept" XML system that displayed documentation from the new application in a web browser, integrating custom settings in the product into the topic. When these settings were changed, the documentation reflected these changes. Based on this proof of concept, Ontario Systems developed a plan to provide dynamically assembled documentation by storing components of documentation attached to various application elements, along with code to "populate" the topics with the settings and options specified in the application. When requested, document components would be assembled and "fleshed out" with these application settings, options, and other information from the application. Once the requested information was assembled, it would be formatted with XSL and delivered to a web browser. Challenges One of the primary challenges that faced Ontario Systems was a lack of experience with XML. A second challenge was that our new application was only partially complete. However, Ontario Systems concluded that XML was the appropriate technology. To alleviate risk from the unknowns in XML, Ontario Systems contracted DTD design services from The Rockley Group, whose work I knew from STC. TRG worked with the entire team to develop the document analysis. In addition, we licensed Epic Editor from ArborText, because of their rich tool set and reputation for high quality service. It was also decided that I would take all of the classes from Arbortext needed to become a certified XML Application Developer. As a part of our tools, Ontario Systems selected Astoria for our content management system (CMS). While both Epic and Astoria provided substantial challenges for our writers, purchased training helped our writing team get up to speed. In addition to learning to manipulate the tools, the entire writing team needed to write with one voice, so that assembled components could be merged to form a cohesive whole. Forming a writing standards committee to produce extensive and detailed writing standards helped to achieve this. Having worked with Epic and Astoria now for about four years, we are pleased with the products and our progress. Benefits & Outcome This project benefits both Ontario Systems and our customers. In the past, it was difficult for everyone who needed documentation to get access to the printed manuals. With our new process, we can deliver documentation to anyone who uses the application. Furthermore, the documentation can be accurate to an application that is "highly customizable." This should reduce calls to our product support center. We have completed our first installations of the new product, and have delivered our documentation with the application. It is also encouraging that the sales staff has requested our IT department to make sure their laptops will activate the documentation. Dynamic documentation has become a key part of sales demonstrations. Lessons Learned Allowing the entire Technical Communication team to participate in the document analysis process was very effective, and led to a high level of acceptance for the new processes. Having a consultant lead initial document analysis and DTD design was effective. Learning to produce modular document components has been a challenge for our Technical Communicators. Consistent language style is key. Having the certified application developer training for Epic makes it much easier to extend our document development functionality. Selecting good tools makes the work go better. Purchasing training was a wise decision.